InfoMagic Internet Tools 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / info-service / gopher / Rice_CMS / gopher24.readme < prev next >

Wrap

Text File | 1993-01-25 | 17.6 KB | 413 lines

WELCOME Welcome to GopherSpace! I hope you enjoy your trek. The InterNet Gopher (or just "gopher" for short) is a simple information dispersal tool based on TCP/IP. It is an example of the kind of seemless interoperability that is possible when we (programmers) actually try to do things right. The Gopher protocol doesn't care about host operating systems, their file storage formats, character sets, or command suite (or lack thereof). CMS Gopher is based on three very strong tools: the REXX language, Arty Ecock's RXSOCKET, and CMS Pipelines. As a programmer, I literally went to tears over how well these three work together. More warm fuzzies later. You need to unpack this thing. ------ ------ ------ ------ ------ ------ ------ ------ ------ UNPACKING CMS Gopher is packaged in several forms. Pick your favourite de-archival tool and start unpacking. Both server and client can reside on the same disk. (that's how they are at Rice) CMS TAR: (Rick's choice) Enter the command: tar xvf gopher24 = = fm where fm is the filemode of the disk or SFS directory to hold Gopher. CARDDUMP: (Cornell 'CARD' format) You may need to reblock the binary file with ... | FBLOCK 80 | ... , then PUNCH it to yourself, order it to the top of your reader, and CARD LOAD * * fm to get the package onto the disk you want. CP SPOOL PUNCH TO * PUNCH GOPHER24 CARDDUMP (NOHEADER CP ORDER RDR spoolid CARD LOAD * * fm READCARD: This is a plain-text archive, which means that executables are not included. You'll have to acquire RXSOCKET MODULE and other binaries via some other means. You'll have to generate the message repository manually. PUNCH the file to yourself with the (NOHEADER option, order it to the top of your reader, then READCARD * * fm, where fm is the disk or SFS directory where you intend to load CMS Gopher. CP SPOOL PUNCH TO * PUNCH GOPHER24 READCARD (NOHEADER CP ORDER RDR spoolid READCARD * * fm LISTSERV: Send a message (with either TELL or MAIL) to LISTSERV@RICEVM1 (LISTSERV@RICEVM1.RICE.EDU), get gopher24 package In CMS that's: TELL LISTSERV AT RICEVM1 GET GOPHER24 PACKAGE LISTSERV will send you everything. No archive extraction needed. ------ ------ ------ ------ ------ ------ ------ ------ ------ SETTING UP THE CLIENT You may have some special method of giving users access to your CMS applications. At Rice, we keep most applications on their own minidisk, and leave a "wrapper" EXEC on a public, always accessed minidisk (our X disk). The client is GOPCLI. Whatever wrapper you create should check for GOPCLI EXEC and access the right disk or SFS directory if it's missing. You may want to tailor a couple of environment variables. There's no CONFIG file for the client in CMS Gopher 2.4. All configuration data are kept in user GLOBALVs. See HELP GOPHER for a list of user-settable Global Variables. HOST and NAME are two that many people like to predefine. HOST is the TCP/IP host computer where your "top level" gopher server runs. NAME is the name of that "top level" menu. (there's no way in the Gopher protocol for a menu to name itself; all menus and plain files are named by the menu that references them, so you need to set NAME or you'll get "(root menu)", harmless but ugly) Note that the client reserves the fileid VMGOPHER DOCUMENT for times when it needs to write a file to CMS disk and can't use the name provided by the current gopher server. PICTURES CMS Gopher 2.4 supports the gopher "image" (type I) files. Presently, the only format displayable is GIF files using the VMGIF package available from the fine folks at BLEKUL11. ------ ------ ------ ------ ------ ------ ------ ------ ------ SETTING UP THE SERVER The server is GOPSRV. Setting it up is trickier than setting up the client because you not only have to create a virtual machine for it to run in, but you also have to take the time to structure your gopher data nicely. See GOPHERD DIRECT for an example CP Directory entry. You can have multiple gopher servers. If you don't have SFS, you can create a hierarchical set of menus using FILELISTs. Some VMers insist on using FLIST. They say it's faster than FILELIST. Fine. But FILELIST lets you save and load FILELISTs such that you can easily bundle files together almost as easily as with true directories. If you do have SFS, you can let it do the work of maintaining your menu hierarchy. Gopher FILELISTs are made up of lines of the form: fn ft fm path "name" type where fn/ft/fm are the filename, filetype, and filemode of the file being referenced. The path is really only the last partof the gopher "selector string" pointing to this file. The paths of all parent menus are automatically prepended. The name (must be in quotes) is what the user sees in the menu referencing this file. The type is a one-digit type indicator, any of: 0 this file is plain-text 1 this item is a menu 4 this is a Macintosh file 5 this is an MS-DOS file 6 this is a UUEncoded file 7 this item is a search on a menu 9 this is a binary file I image (graphic; typically GIF) s sound There are other types, but these are the ones most useful in FILELISTs. Everyhing except the filename is optional. Filetype, filemode, path, name and type may all be omitted, in which case the server will choose. The first character of each line in a Gopher FILELIST must be either a blank or an asterisk, the latter denoting a comment. With care, you can in fact use a Gopher FILELIST as input to CMS' FILELIST EXEC) I mentioned the menu type, digit 1. Please note that you do NOT specify a menu within a menu by marking some file as type 1, but rather by using a special filetype "*". The server will automatically mark it as type 1. The "root" menu is defined by <userid> FILELIST, where <userid> is the name of your gopher server virtual machine, typically GOPHERD. You can override this and other parameters in GOPHERD CONFIG. So, making a long story longer, to setup your gopher server, define virtual machine GOPHERD, give it access to your local gopher disk, create GOPHERD FILELIST listing one or more files you wish to serve-out, then CP AUTOLOG GOPHERD. There is a CONFIG file, which you can tailor as needed. With the 2.4 server, the only variables meaningful in the config file are LOGPIPE, PORT, and ROOT. PORT defaults to 70. ROOT defaults to the virtual machine name (server's userid). LOGPIPE defaults to CONSOLE. You will probably want to dedicate port 70 to GOPHERD in your local PROFILE TCPIP for you TCPIP service virtual machine. It's also good to have GOPHERD listed as AUTOLOGged by TCPIP. Neither of these steps are required to test GOPHERD; just run it. It's pretty harmless. PIPES AND AUTHORIZATIONS A nice way to degrade performance of your gopher server is to create a NAMES file for a menu. In spite of the cost, this is useful because you can control access to and/or define CMS Pipelines specifications for menus and items in a NAMES file. When the server accesses a directory, it looks for <menu> NAMES. (this works best with FILELISTs; if you do it for SFS directories, consider that the server may access other directories, releasing the one that holds your NAMES file, as it resolves the selector path string) If <menu> NAMES exists, the server uses NAMEFIND to process it. This is best explained by an example: :nick.myfile :fn.my :ft.file :auth..rice.edu deny .cuny.edu .gov allow * :pipe.CP Q NAMES | SPLIT /,/ For the file MY FILE, any host who's InterNet hostname ends in ".rice.edu" (all of the Rice campus) can read it. Any host who's InterNet hostname ends with ".cuny.edu" or ".gov" is prohibited. Everyone else is then permitted. If the client host is allowed access, then instead of reading the file MY FILE, the server sends the output of the pipeline CP Q NAMES | SPLIT /,/ to the client. This can get quite sophisticated. No, you do not have to have both an auth and a pipe in the NAMES file entry. You can have either one or neither. And know that CMS NAMEFIND does not provide a way to specify the filemode of the NAMES file, so be careful about menu name collisions. You can also specify host, port, path, name, and type in a NAMES file. This means that you can use NAMES files in place of GOPHER (link) files, but remember that NAMEFIND is going to cost you. Link files? They let you point to other gopher servers. See the Q&A section below, otherwise this section will go on forever. SEARCH ITEM Creating a search item in a menu is easy. Set it up just like you would any other sub-menu, but mark it as Type 7. Something like: MYSEARCH FILELIST * whatever "My Own Search Item" 7 in the parent menu's FILELIST, or, :nick.whatever :fn.mysearch :ft.filelist :type.7 There's no reason why you can't have the menu as a whole available right next to the searched version, like: MYSEARCH FILELIST * whatever "My Own Search Item" 7 MYSEARCH FILELIST * whatever "My Own Search Item (not indexed)" You must also create an index file for this menu. The easiest way is by using GOPGEN. GOPGEN is primarily a tool for making your own mods to CMS Gopher, but it also performs the right incantation on WISHLG (thank's Yossie) to create an index for you. The server then will invoke WISHLP (thank's again, Yossie) to list the files that match the client's search expression. GOPGEN INDEX MYSEARCH MYSEARCH FILELIST must exist. All of the files it lists must exist. You must then put the index file, MYSEARCH GOPINDEX, where the server will access it. ------ ------ ------ ------ ------ ------ ------ ------ ------ FUNCTIONS OF FILES Here's a list of most of the files in the package and their function: GOPHER EXEC "wrapper" EXEC; ensures product disk accessed GOPCLI EXEC the client GOPCLINI EXEC client initialization (called once from GOPCLI) GOPCLTCP REXX handles all TCP/IP work for the client GOPCLITM REXX decides what how a given item should be processed GOPCLIST REXX displays connection status, "Reading ...", etc GOPCLIMB REXX menu browser GOPCLIUI REXX user input (prompting) GOPCLTXT REXX reformats plain-text GOPCLIFV REXX file viewer; may be used stand-alone GOPCLIGV REXX graphics viewer; presently GIFs only GOPCLIFI EXEC returns legal CMS fileid from a gopherspace path GVM EXEC "DIALed Gopher" client; calls GOPHER to call GOPCLI GVM DIRECT CP Directory entry for the DIALed Gopher GOPHERD EXEC "wrapper" EXEC for the server; write your own GOPSRV EXEC the server GOPSRVLS REXX lists files and menus (menus in LISTFILE format) GOPSRVRP REXX gopher path resolution; uses GOPSRVLS output GOPSRVMB REXX menu builder GOPSRVGL REXX gopher "link" processor GOPSRVAU EXEC performs authorization check GOPSRVFM EXEC dummy filemode function for server GOPHERD DIRECT CP Directory entry for the server EXPAND REXX expands TAB characters PRINT REXX similar to CMS PRINT, but a pipe A2E REXX translate ASCII to EBCDIC E2A REXX translate EBCDIC to ASCII TCPA2E REXX A2E, but follows TCP/IP translate tables TCPE2A REXX E2A, " " " " " STANDARD TCPXLATE suggested ASCII <---> EBCDIC translate tables STANDARD TCPXLBIN binary object built from above TCPXLATE GOPUME MESSAGES message repository source GOPUME TEXT message repository object GOPXEDPR XEDIT XEDIT profile for XEDIT used as file viewer GOPXEDII XEDIT "item info" command for XEDIT as file viewer GOPHMARK EXEC migrates bookmars from 2.3 RXSOCKET MODULE Arty's wonderful CMS Socket tool RXSOCKET MODULESP VM/SP and VM/HPO version of above DISKWRIT MODULE minidisk need reACCESSing? WISHLP MODULE Yossie's *fast* search engine WISHLG MODULE index builder for above PH EXEC Nick LaFlamme's CSO/qi (phonebook) client GL EXEC primitive tool for browsing CMS Gopher FILELISTs GOPHERCAT EXEC dumps gopherspace files right onto your console GOPHERDH REXX a pipeline stage that interprets CMS HELP HELP NAMES defines HELP menu to the server using above ------ ------ ------ ------ ------ ------ ------ ------ ------ There is a discussion list, VMGOPHER@PUCC.Princeton.EDU. There is another CMS Gopher (both server and client), popularly called "the Vienna Gopher", available from Gerhard Gonter <GONTER@AWIWUW11>. ------ ------ ------ ------ ------ ------ ------ ------ ------ Q: The basics, documents and FILELIST menus, is fairly easy to grasp, but the relationship of a NAMES file and its entries to a FILELIST file and its entries is not at all evident to the poor soul that just wants to provide an information service without much time invested (I.e., without subscribing to VMGOPHER). A: The easiest way to start is just name some plain-text files in GOPHERD FILELIST (which are available to your GOPHERD service machine on an accessed disk or SFS directory). Then after you're comfortable with that, try some "links" (filetype GOPHER) and sub-menus (filetype FILELIST). Then get into NAMES files. Q: How to I point to another server/menu? A: The easiest way is with a "link" file (filetype GOPHER). When a link file shows-up in any FILELIST, the contents of that file are read and the information specified is presented to the client for that particular menu item. The contents of a GOPHER (link) file are the same as for a UNIX server link file, of the form: name=Rice University CMS Gopher server host=ricevm1.rice.edu port=70 path=1/ type=1 As of 2.4, GOPHER file can have more than one link in it. Q: How does a GOPHER file differ from a "link" in a NAMES file? A: The NAMES file is far more extensive. (and exPensive) With the CMS Gopher server, you don't use "link" files to override the characteristics of other files in the menu (as you would with a UNIX server). With the CMS server, GOPHER (link) files are exclusively used to reference other network (usually non-local) resources, while the NAMES file may apply to local files, which reside on your system OR to remote services. Q: Some folks have made it seem that their gopher server files are free for the taking ... is there a gopher feature to pull these in? A: To "receive" (keep) an item, press PF5. The receive function will not overwrite an existing file (though you can still view & SAVE from XEDIT). Q: GOPHERD should document DISKWRIT in the prolog. A: GOPHERD uses DISKWRIT to perform the same "reaccess" trick that GONE EXEC does when you reconnect. If disks appear to have changed, they are reACCESSed so that the server has the latest revision of any files on those minidisks. Q: Why are the "STANDARD" translate-table files provided? Are these for use with the server? A: Both server and client. The default ASCII <---> EBCDIC translation in VM TCP/IP (FAL) is not 100% correct for the majority of the VM/UNIX/VMS/DOS/Mac world we live in. STANDARD TCPXLATE and TCPXLBIN provide a 1-for-1 translation between de-facto "network EBCDIC" (codepage 1047) and "extended ASCII" (ISO 8859-1). Q: If PhoneBk and Search are available, how do we use them? A: Presently, CMS GopherD does not support PhoneBk and Search engines. The client (GOPCLI) is happy to utilize such servers on other hosts. Q: Some GOPHERs restrict access or output to some clients; how? A: Specify an "auth" value in the NAMES file. The tag :auth. allows for control over any object in a menu (defined by a FILELIST and/or NAMES file), even the menu itself. Q: Is there anything different about your RXSOCKET? A: RXSOCKET is supplied because Gopher requires it. RXSOCKET was created by Arty Ecock. He maintains it. Rice doesn't have any mods to RXSOCKET, and Gopher doesn't need any special treatment from RXSOCKET. If you find an RXSOCKET packaged with CMS Gopher to be out-of-date, by all means, use the current one or get the latest from Arty. If you pick-up RXSOCKET MODULE from a UNIX FTP host, you must "deblock" it back into its CMS form (record oriented) with: PIPE DISK RXSOCKET U-MODULE | DEBLOCK CMS | DISK RXSOCKET MODULE ------ ------ ------ ------ ------ ------ ------ ------ ------ Thanks to: Yossie Silverman, Jim Gerland, Arty Ecock, Serge Goldstein, Chuck Boeheim, Wayne Smith, Jim Colten, Nick LaFlamme, Rich Wiggins, Martha McConaghy, John Hartmann, Melinda Varian, ... (this list continues to grow, and some have surely been left out)